                     The 'Drlink' AOF Linker
                     ~~~~~~~~~~~~~~~~~~~~~~~

Disclaimer
~~~~~~~~~~
The 'Drlink' linker is provided 'as is' and people using it do so
entirely at their own risk. No liability whatsoever will be
accepted for any loss or damage arising from the use of this
software.


Introduction
~~~~~~~~~~~~
Drlink is a linker that is intended to be a partial substitute for
the Acorn linker, 'link'. It is aimed at people with compilers
that generate object files in Acorn's AOF format but who do not
have a copy of 'link', for example, people who want to use the DDE
Pascal compiler or TLA or perhaps their own homebrew compilers.
Drlink accepts object files in Acorn's AOF format and libraries in
Acorn's ALF format and links them to produce an executable image
in either Acorn's AIF format or a plain binary image. It can also
be used to link relocatable modules or to create partially-linked
AOF files. Drlink is modelled very closely on the version of
'link' that comes with release 3 of Acorn's C compiler but it is
not really a complete replacement for it as it does not have the
same range of facilities. What is there, it is hoped, should be
adequate in most cases. Drlink is designed to link 'ordinary'
programs and cannot do some of the fancy things link can, such as
create image files that use overlays. Of course, some of these
features could be added at a later date but the current version of
Drlink does not support them. On the other hand, it does
contain some features found on later releases of 'link' such as
the ability to increase the size of the wimpslot if necessary when
running in a task window and support for extended command lines.
Other features include the ability to scan libraries more than
once when resolving symbols and, assuming the right compiler
options have been used when compiling programs, being able to
leave out unused functions from executable images. Hopefully
features like these will make the linker attractive to people who
use link as well.


Thanks...
~~~~~~~~~
I would like to thank the many people on Arcade who have tested
Drlink for me over the months and who made many helpful and useful
suggestions. Drlink would never have reached the state it has
today without their generous assistance.


Using Drlink
~~~~~~~~~~~~
Drlink is a command line-based program and has the same command
syntax as 'link'. It can be used in the same environments as
'link', for example, with amu. If it is renamed as 'link', then
it can be dynamically invoked from either the Acorn C or DDE
Pascal compilers as well. It accepts the same options as 'link',
although a number of them are unsupported and will be flagged as
errors. Drlink also supports extended command lines. (Further
information on this can be found in the section 'Extended Command
Line Support' below.)

The command syntax is:

    drlink <list of files> <options>

where:

<list of files> is the list of object files and libraries to be
                included in the linked program.

<options>       is the options to be used when linking the
                program.

Options and object file names can be freely intermixed. The linker
processes all the options before moving on to the link itself.

Filenames
Each filename in the list of object files should be fully
qualified, that is, Drlink makes no assumptions as to where the
object files are to be found. Wildcards are permitted, in which
case Drlink loads all the files that match the wildcard. If the
directory containing the object files is called 'o', then Drlink
will also accept 'back-to-front' filenames, for example, 'sieve.o'
instead of 'o.sieve'. If a path is used as part of a filename, for
example, 'C:', the way Drlink treats the filename depends on
whether it contains wildcards or not. If it does not, then every
directory on the path will be searched to find the file until
either the file is found or the end of the list is reached. On the
other hand, if the filename contains wildcards, only the first
directory listed on the path will be checked. (This is how link
behaves.) Examples:

    o.sieve
    o.dhry1 o.dhry2 c:o.stubs
    o.dhry* c:o.ansilib
    dhry*.o c:ansilib.o
    o.* c:o.*
    O.world scsi::Arc.$.programs.!Pascal.O.Plib C:O.stubs

Drlink ignores the case of object file and library names.

Options
As noted above, Drlink recognises the same options as 'link',
even if it does flag a number as unsupported, plus has a number of
its own. Options take the form of a '-' followed by the option
name. Some options are followed by an argument. One or more blanks
should be left between the option name and the argument. The case
of the option and any argument is ignored. Options that are
supported are:

    -aif       Create an AIF image file.

               This is the standard format for programs running
               under RISC OS where a small header is attached to
               the start of the program containing various bits
               and pieces of information. It is the default option
               used for the image type when no type is explicitly
               given unless the '-base' option is used when '-bin'
               is the default value.

    -aof       Create a partially-linked AOF file.

               The image file created takes the form of an AOF
               file where as many references as possible between
               the object files included in the link are resolved
               and then the object files are merged together to
               form another object file in AOF format that can be
               used in a future link.

               There are a couple of points to watch out for here:
               a) To include debug information in the AOF file,
                  either '-debug' or '-keepdebug' must be used.
               b) All local symbol names are lost, so they will
                  not appear in the low-level debug tables if
                  these are generated in the final image.

    -base <address>
               This option allows the initial load address of the
               read-only part of the image file to be specified.
               The read-only part normally contains code.
               <address> is taken to be decimal by default but if
               prefixed by '&' or '0x' it will be treated as a
               hexadecimal value. It can be postfixed by 'k' or
               'm' to indicate the address is in kilobytes or
               megabytes. The case of the 'k', 'm', 'x' or any of
               the hex digits 'a' to 'f' is ignored. The value of
               <address> is rounded up to the next word boundary
               if it is not already so aligned.
               
               The initial load address can only be specified for
               a binary image file.
               
               Image files created when this option is used do not
               have a filetype but have 'load' and 'execute'
               addresses instead. The load address is set to
               whatever was specified on '-base' and the 'execute'
               address to the program's entry point address. The
               files themselves contain plain binary images as
               created by the option '-bin'. This behaviour is
               different to that of 'link'. 
               
    -bin       Create a plain binary image file.

               A binary image file does not have the header that
               AIF files have on them and consist of nothing but
               the linked program. This has two consequences.
               Firstly, and most importantly, zero-initialised
               data areas will not be cleared to zeros when the
               program starts running as the routine to do this is
               part of the AIF header. Secondly, if debugging
               tables are included in the executable image, there
               is nothing to indicate where they are.

               Note that when the option '-base' is used and the
               image file type is not given, '-bin' is assumed to
               be the image type.

    -c++       Perform C++-specific operations (only relevant for
               Norcroft compiler).
               
               C++ requires the symbols '__link' to be chained
               together to form a list which can be accessed through
               '__head'. This is used to call constructor and
               destructor functions.

    -case      Ignore the case of symbols when trying to resolve
               symbol references. If this option is omitted, then
               the case of the letters in symbol names is treated
               as significant.

    -debug     Include debugging information in the image file. If
               this option is omitted, any debugging tables
               generated by the compiler that produced the AOF
               file will be left out of the final image file. If
               it is specified then any debugging tables found
               will be included, along with some low-level tables
               the linker itself creates. In the case where the
               AOF files to be linked do not contain debugging
               tables, only the linker's low-level tables will be
               included.

               There is a second debug option, '-keepdebug', that
               can be used to selectively include debugging
               tables. Only one of '-keepdebug' or '-debug' should
               be used. If both options are used, '-debug' takes
               precedence.

               Note that if this option and '-bin' is used then
               the debugging tables will still be included
               although they will not really be of much use as
               debuggers such as 'asd' would not be able to find
               them. On the other hand, a routine in the program
               might be able to locate them and for this reason
               they are still included in the image file.

    -edit <name>
               Gives the name of a file from which 'link edit'
               commands are to be taken. For more information,
               refer to the section 'Link Edit Commands' below.

    -help      Print a summary of Drlink options.

    -map       Print a list of areas (read-only code, data,
               debugging tables, etc) in the image file giving
               their addresses, sizes and types and the name of
               the original AOF files that contained the areas.

    -module    Create a relocatable module in RMF format.

    -output <name>
               Write the executable image file to file <name>. If
               this option is omitted, the program is written to
               the file '!Runimage' in the current directory.

    -relocatable
               Create a relocatable AIF image file.

    -rmf       Create a relocatable module in RMF format.

    -verbose   Print messages as the link progresses saying how
               far it has got. Some extra warning messages are
               also produced if the linker finds aspects of the
               link that look a bit iffy, for example, it will
               print warning messages about unresolved 'weak'
               external references. Normally, the linker keeps
               quiet about such things.

               Note that '-quiet' takes precedence over
               '-verbose'. If both options are specified,
               '-verbose' is ignored.

    -via <name>
               According to the documentation on 'link', this
               option allows the list of files to be included in
               the link to be specified in file <name>. In fact,
               the file can also contain link options and this is
               how the option '-via' has been implemented in
               Drlink. When this option is encountered, input is
               switched to the file <name> and the list of files
               and options taken from that file until end-of-file
               is reached whereupon input reverts back to the
               command line. The only option that is not valid in
               a '-via' file is '-via'. This option can be used
               as many times as is necessary on the command line.
               The format of the filenames and options in the file
               <name> is exactly the same as when specified on the
               command line, except they can be spread over as
               many lines in the file as necessary. Any 'newline'
               characters in the file are treated as if they were
               blanks.

    -workspace <size>
               For a relocatable AIF image file, reserve <size>
               bytes of memory after the image when relocating
               it. <size> is rounded up to a whole number of
               words. <size> is taken to be decimal by default
               but can be prefixed by '&' or '0x' to give a
               hexadecimal value. It can be postfixed by 'k' or
               'm' to indicate the size is in kilobytes or
               megabytes. The case of the 'k', 'm', 'x' or any of
               the hex digits 'a' to 'f' is ignored.

All other 'link' options are recognised but are unsupported. They
are: dbug, entry, overlay and xref.

The linker has the following extra options of its own:

    -acornmap  If option '-symbols' is used to print a symbol
               listing, then it will be created in a format
               similar to that produced by 'link'.

    -areamap <name>
               This option causes the linker to write a map of the
               areas in the executable image to file <name>. If
               option '-nounused' is used as well, a list of areas
               left out of the image file is produced as well. The
               format of the list is exactly the same as that
               produced by the '-map' option.

    -data <address>
               '-data' allows the address of the start of the
               read/write portion of the image file to be
               specified. <address> is assumed to be a decimal
               value by default but prefixing it with '&' or '0x'
               means it will be taken to be in hexadecimal. It can
               be postfixed by 'k' or 'm' to indicate the address
               is in kilobytes or megabytes. The case of 'k', 'm',
               'x' or any hex digits is ignored. The value of
               <address> will be rounded up to the next word
               boundary.

               This option can only be used when linking a binary
               image file. Other image formats, for example, AIF,
               make assumptions as to where the read/write part of
               the image is to be found and therefore use of
               '-data' is restricted to binary files only.

               The linker built-in symbol 'Image$$RW$$Base' is set
               to the address of the start of the read/write
               portion of the file, so the address of the data
               can be found in a program by including a reference
               to this symbol.

               Note that this option should only be used with the
               greatest of care. It allows the address of the
               start of the read/write portion of the image to be
               given. The point of this is to allow data to be
               placed at a specific address in memory. However, it
               is also possible for executable code areas to go in
               the read/write part of the image. If '-data' is
               used, any such code will be treated as though it
               will be at <address> at run time but due to the
               format of the image file, when the program is run,
               the code will not be placed at <address>. The same
               is true for any pre-defined data. Therefore, if
               this option is being used, the following points
               should be observed:

               1.  Executable code should be placed in read-only
                   code areas only.
               2.  Constants should be placed in read-only data
                   areas only.
               3.  The initial values of any other items of data
                   will be undefined.

    -debimage  If this option is specified and the image file to
               be written contains debugging tables, the filetype
               of the image file is set to 'DebImage' instead of
               'Absolute'. If this option is not used, the
               filetype of the image file is always set to
               'Absolute'.

    -gcc       This option is used in conjunction with '-nounused'
               to tell the linker to ignore special areas created
               by GCC when weeding out areas that are not
               referenced in the image file. It has no other
               effect. The default is to omit all unreferenced
               areas.

    -keepdebug <file list>
               The purpose of this option is to allow debugging
               information to be included selectively in the image
               file. <file list> is a list of the object files and
               library members where any compiler generated
               debugging tables found are to be kept. Debugging
               tables in any other files or members are ignored.
               Any linker-generated low-level debugging tables
               will only include entries for the files in <file
               list>.

               The format of <file list> is a string of names of
               files and library members separated by commas with
               no other intervening characters or a string of
               names enclosed in double quotes separated by one or
               more blanks. The names should exactly match the
               names of the files or library members to which they
               refer, although the case of the names is ignored.
               Wildcarded names are not permitted, although the
               case where a name in <file list> matches a file
               name in the list of files to link that resulted
               from expanding a wildcarded name is allowed.

               Only one of the debugging options should be used at
               a time. If both are found on the command line then
               '-debug' takes precedence over '-keepdebug' and the
               image file will contain all the debugging tables
               the linker finds.

    -leaveweak This instructs the linker to leave weak externals
               unresolved if satisfying them would cause library
               members to be loaded. This is the way the AOF
               version 3 documentation says the linker should
               behave, and is the opposite to the AOF 2 docs. By
               default, Drlink will attempt to resolve weak
               externals. This options makes it behave as per AOF 3.

    -lib <library list>
               <library list> is a list of libraries that Drlink
               will search when attempting to resolve symbol
               references. The list can take two forms. Either it
               can supplied as a string of library names separated
               by commas with no intervening blanks or any other
               white space characters or the list can be enclosed
               in double quotes with the names separated by one
               or more blanks. Wildcarded library names are not
               permitted.

               This option should not be needed in the normal
               course of events. Drlink can tell the difference
               between AOF files and libraries without having to
               be told which is which but this is not the purpose
               of the option. Its purpose is to reduce the
               amount of memory used by the linker. The way the
               Drlink works is to read *all* the files given on
               the  command line into memory including any
               libraries. Whilst this speeds up pulling members
               out of the libraries, it can be quite expensive in
               terms of memory. Libraries specified after '-lib'
               will not be brought into memory and members will
               be loaded from them as required.

               Note that any 'old style' libraries listed after
               '-lib' will be loaded immediately, that is, they
               will not be added to the list of libraries to be
               searched later.

    -linkersets
               This option is similar to the -c++ option, but supports
               a generalised form of the chained symbols. All symbols
               prefixed by '__link' will be chained together with the
               same named symbols. The start of each chain will be
               stored in the symbol with the prefix '__head' and the
               same suffix as the '__link' symbol. For example, all
               symbols with the name '__link_init' would be chained
               together and could be accessed through the symbol
               '__head_init'.
               
               The '__link' symbols must be local.
               The '__head' symbols must be global.

    -nounused  This option is used to control whether unreferenced
               areas in the image file will be left out. By
               default, all areas are left in but if '-nounused'
               is specified, the linker checks each area in the
               executable image and leaves out any that it finds
               are not referenced by any other areas.

               The purpose of this option is basically to strip
               out any unused functions in a program. To achieve
               this, it is necessary first to compile the program
               with the '-zo' C (and DDE Pascal) compiler option.
               This has the effect of splitting each function up
               into its own self-contained 'area' in the object
               code file. If '-nounused' is specified, the linker
               examines all the areas and discards any that it
               finds are not referenced from any other areas. In
               fact, if the linker finds that, as a result of
               throwing away an area, others that it referenced
               now become unused, it will discard those other
               areas as well. Unfortunately, it will not detect
               cases where there are loops, that it, if area 'a'
               calls only area 'b' and area 'b' calls only area
               'a', it will not detect that it is safe to throw
               away both areas. On the other hand, it can handle
               the case where an otherwise unused area calls only
               itself.

               Note that if the '-verbose' option is used, Drlink
               will print a list of areas that have been left out
               of the image file, along with the name of the first
               symbol in the area if it can find one. This should
               hopefully be the name of the function contained in
               that area in an AOF file produced by the C
               compiler.

               This option is not present in the C release 3
               linker but it might be available in other AOF
               linkers.

               WARNING: It should be remembered that the '-zo' C
               compiler option is undocumented. In versions 3 and
               4 of the compiler, it contains a serious bug that
               affects the addresses of character strings in the
               executable image. Under certain conditions, these
               addresses are *wrong*. There is a workaround for
               this, however. If '-zo' is used then '-fw' should
               be used as well, that is, you should say, for
               example: 'cc -zo -fw -c c.world'.

    -pagealign Pagealign instructs the linker to align the end of
               the last read-only area in the image file on a page
               boundary. The pagesize of the machine on which the
               linker is being run is used in the calculations.

    -quiet     This instructs the linker not to print the
               'Drlink AOF Linker ...' message when it starts
               up. Nothing will be printed except for error
               messages. This option overrides '-verbose' if
               both are specified.  This option will be ignored
               when '-strict' is specified.

    -rescan    This tells the linker to scan libraries more than
               once if necessary when searching for symbols.
               'link' scans them only once so it is important to
               specify libraries in the correct order. Drlink also
               works like this unless '-rescan' is used, in which
               case it will continue searching the libraries in
               the order in which they were specified on the
               command line until all symbols have been found or
               all libraries have been checked for a particular
               symbol.

               This option is not present in the C release 3
               linker but it might be available in other AOF
               linkers.

    -revmap    This option is used in conjunction with '-symbols'
               and instructs the linker to list the symbols with
               one symbol per line in the order <address> <name>.

    -symbols <file>
               Create a file listing all the relocatable symbols
               in the image file. They are listed in address
               order.

               If option '-acornmap' is used, the symbol listing
               will be produced in a format similar to that of
               'link' instead of using Drlink's format, that is,
               one symbol per line in the order <name> <address>.

               If option '-revmap' is used then the symbol listing
               is produced with one symbol per line in
               <address> <name> order.

   -strict
               Treat warnings as errors.  Specifying this option
               will ignore option '-quiet'.

   -throwback  If this option is used and it is possible to use
               'throwback' then all warning, error and fatal error
               messages will be displayed in a 'throwback' window.
               Note that only errors found after the option has
               been encountered in the command line will be sent
               to the 'throwback' window. Any found before that
               point as well as any informational messages will
               still be displayed at the command line in the
               normal way. To display all errors in the
               'throwback' window, this option should be the first
               one supplied on the command line.

               Note that in order to use this facility, it is
               necessary to have the 'DDEUtils' module loaded and
               an editor that supports 'throwback', for example,
               Dominic Symes' editor, !Zap.

               Note that the 'throwback' file name is set to that
               of the image file to be created, and the effects of
               clicking on one of the error messages shown in the
               window is undefined. 'Throwback' is meant to be
               used for source files, not object code!

Note that most options can be abbreviated to one or two letters.
The minimum abbreviation for each option is:

    -acornmap    -aco
    -aif         -ai
    -aof         -ao
    -areamap     -area
    -base        -b
    -bin         -bi
    -case        -c
    -data        -da
    -debimage    -debi
    -debug       -d
    -edit        -e
    -gcc         -gcc
    -help        -h
    -keepdebug   -keep
    -leaveweak   -leave
    -lib         -lib
    -map         -map
    -module      -m
    -nounused    -no
    -output      -o
    -pagealign   -pag
    -quiet       -qui
    -relocatable -r
    -rescan      -res
    -revmap      -rev
    -rmf         -rm
    -symbols     -s
    -throwback   -th
    -verbose     -v
    -via         -via
    -workspace   -w

Examples:

    drlink o.sieve c:o.stubs
    drlink sieve.o c:stubs.o
    drlink o.dhry1 o.dhry2 c:o.ansilib
    drlink o.dhry1 o.dhry2 c:o.stubs -o dhry
    drlink o.* -no -o PDC
    drlink o.life c:o.risc_oslib c:o.stubs -map -v
    drlink o.life -lib c:o.risc_oslib,c:o.ansilib
    drlink o.life -lib "c:o.risc_oslib  c:o.ansilib"
    drlink -throw o.balls64 p:o.plib c:o.risc_oslib P:O.Stubs
    drlink o.balls64 -via pasclibs -map -v

The default options are to generate an AIF image file, to treat
the case of symbols names as significant, not to include debugging
information, to include all areas in the image file, not to
produce an area map or symbol listing and to keep quiet about what
the linker is doing.

In normal use, it should not really be necessary to use any of the
linker options and running Drlink should just be a case of
typing the command and the list of files and libraries to include
in the linked image file, perhaps using the '-d' option to include
debugging tables or '-o' to change the name of the linked image
file. 


Return Codes
~~~~~~~~~~~~
If a link works, Drlink gives a return code of zero. If it fails,
it posts a return code of twelve. A fatal error produces a return
code of sixteen.


Extended Command Line Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Drlink can make use of the extended command line facility that
is provided by the 'DDEUtils' module. This allows the command line
passed to Drlink to be of any length and not restricted to the
normal limit of 255 characters. If the linker finds there is an
extended command line available, it uses that in preference to the
standard command line, which it completely ignores.

In order to use this facility, it is necessary to have the module
'DDEUtils' loaded and to use software that can set up extended
command lines, for example, the version of 'amu' that comes with
release 4 of the C compiler. 


Link Edit Commands
~~~~~~~~~~~~~~~~~~
This is a feature that allows symbols in the AOF files to be
edited in various ways. Four operations are possible:

1.  Rename a symbol in an AOF file.
2.  Change a symbol reference in an AOF file.
3.  Hide a symbol in an AOF file by making it 'local'.
4.  Reveal a symbol in an AOF file by making it 'global'.

The purpose of these commands is to resolve problems where
different AOF files define symbols with the same name or to enable
what would be unresolved symbol references to be replaced with
references to defined symbols. Note that all that the commands do
is act as a filter on the AOF files before they are passed to the
main link routines and that if, for example, a symbol reference is
changed, then there are no checks to make sure that the new symbol
refers to the same sort of 'thing' as the old.

The commands are read from the file specified on the option
'-edit'. Note that, unlike 'link', multiple 'link edit' files
can be supplied. The general format of the commands is:

    <command> <filename> ( <one or two symbol names> )

<command> is one of the four commands described below and <filename>
is the name of the AOF file or library member that will be
affected by the command. Depending on the command, either one or
two symbol names follows in brackets. The commands are free-form
and can be spread over as many lines as necessary in the file.
Several commands can be stacked on one line and there is no limit
on the number of commands in a file.  At least one space should be
left between the command and the filename but they are optional
after that. The case of the link edit commands themselves is
ignored as is that of any file names, but the case of symbol names
is taken as significant, unless the option '-case' is specified on
the command line as well in which case it is ignored. It is
possible for several commands to refer to the same symbol, so
that, for example, the name of a symbol could be changed in one
file and references to it in another file could also be changed to
that name as well. The order of the commands in the file is, in
general, unimportant, but also refer to the note below. If, on the
other hand, a symbol is to be renamed and its scope changed at the
same time, then both edit commands should refer to the symbol by
the symbol's old name.


Rename a Symbol
The format of the command is:

    rename <filename> ( <old name> , <new name> )

The effect of the command is to rename the symbol <old name>
defined in file <filename> as <new name>. All references to the
symbol should use <newname>.


Change a Symbol Reference
The format of this command is:

    change <filename> ( <old name> , <new name> )

It changes external references to symbol <old name> in file
<filename> to <new name>.

Hide a Symbol
This command's format is:

    hide <filename> ( <symbol name> )

If the symbol <symbol name> in file <filename> is marked as being
visible to any file that references it, its scope is change to
'local' so that it can only be referenced in the file in which it
was declared.

Reveal a Symbol
This command has the format:

    reveal <filename> ( <symbol name> )

If the symbol <symbol name> in file <filename> is marked as a
'local' symbol, that is, can only be referenced in the file file
in which it was declared, its scope is changed to 'global' so that
any file can reference it.

Examples:

    hide o.sieve(main)

    rename o.miscprocs(isalnum,isalfanum)
    change o.lexicals(isalnum,isalfanum)
    change o.preproc(isalnum,isalfanum)

There are a couple of points to be aware of using the link edit
commands.

Firstly, the commands are not executed in the order in which they
are specified. All the commands for one file are performed
together. They are also carried out in the order in which the
files are specified on the command line. As the order in which
library members will be read is not defined, the order in which
link edit commands for these are executed is undefined as well.

There are times when the commands will appear not to work. In a
'C' or DDE Pascal program, if a symbol reference, for example, a
function call, is changed, references to that symbol within the
AOF file will not be altered as the compiler will have resolved
the references at compile time.


A Brief Description of Drlink
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Drlink starts by reading the list of object files and libraries
given on the command line into memory, except for any libraries
given on the option '-lib'. Any 'link edit' commands are acted
upon as the files are read. After this, Drlink attempts to resolve
symbol references in each object file using, first, the symbols
defined as being local to that file and then symbols defined as
available to any file. If there are still any unresolved symbols,
it then goes through each library trying to find them. The
libraries are searched in the order they are specified on the
command line, from left to right. This includes libraries
specified on the '-lib' option. Each library is scanned only once,
unless the option '-rescan' is used.  This means that any library
members read can only refer to symbols that are already known or
that can be found in that library or one that has yet to be
searched. The order that libraries are specified on the command
line is therefore very important. If, on the other hand, '-rescan'
is specified, Drlink will keep searching the libraries until all
the symbols have been found or until it determines that a symbol
cannot be found in any library.

Assuming that all symbol references have been found, Drlink moves
on to resolving addresses. Before it does that, however, if the
'-nounused' option was specified, it attempts to determine the
areas in the program that are not referenced from any other areas
and removes any it finds from the program. Next, it determines the
proper addresses of all the symbols and areas in the program and
then goes through the program relocating and resolving addresses.
If the '-debug' option is used, the low level debugging table is
created at this point. The final step is to write the completed
image file to disk.

Drlink has the ability to increase the amount of memory it is
using if it is running in a task window or using the 'F12' CLI. It
will acquire as much extra memory as it needs and return it once
the link has completed. Drlink can be run in a wimpslot of only
96K bytes.


Pre-defined Symbols
~~~~~~~~~~~~~~~~~~~
There are a number of pre-defined symbols that can be referenced
in object files. These are defined by the linker itself. The ones
that Drlink supports are:

Image$$RO$$Base    The start address of the 'read-only' part of
                   executable image when loaded into memory. This
                   contains program code and constants.


Image$$RO$$Limit   This is the address of the byte after the last
                   byte of the 'read-only' part of a program when
                   loaded into memory.

Image$$RW$$Base    This gives the address of the first byte of the
                   'read/write' portion of a program when loaded
                   into memory. This contains program code and
                   data.

Image$$RW$$Limit   This defines the address of the byte after the
                   last byte of the 'read/write' part of the
                   program. The includes any zero-initialised data
                   areas.

Image$$ZI$$Base    This symbol defines the start address of the
                   'zero-initialised' part of the program when
                   loaded into memory. This is simply an area of
                   memory that is used by the program when it is
                   run to hold data. It is not included in the
                   image file on disk to prevent the image file
                   becoming bloated with huge tracts of
                   uninitialised data (except the Acorn C compiler
                   does not make use of them and so the image
                   file can become bloated with huge tracts of
                   uninitialised data). If an AIF file is being
                   produced (the standard Acorn executable image)
                   then the zero-initialised data area is cleared
                   to zeros when the program is run. This is not
                   case if any other executable file formats are
                   used, for example, '-bin'.

Image$$ZI$$Limit   This marks the address of the byte following
                   the last byte of the 'zero-initialised' data
                   part.

                   It should be noted that, with Drlink, the two
                   symbols 'Image$$RW$$Limit' and 'Image$$ZILimit'
                   are set to the same value.

The Acorn documentation says that the end of one part of the
executable image should not be assumed to coincide with the start
of the next, for example, it should not be assumed that the
read/write part of the image starts the byte after the read-only
part.

The six 'Image$$' symbols are defined in the 'link' documentation
but there are a large number of other undocumented symbols, some
of which are used by the libraries supplied with the C compiler
(the C release 3 libraries, at least). Drlink implements a
number of these but not the whole set, nor are the ones that are
present guaranteed to remain there.

'Area' Symbols
Roughly speaking, the part of the AOF file that contains the
actual code, data and debugging tables compiled from the original
source file is broken down into a number of named 'areas', for
example, the C compiler generates an area called 'C$$Code' for
program code and one called 'C$$Data' for any data. These will be
present in each AOF file included in the link and what Drlink
(and 'link') does is to group all the areas with the same name
together. What is not documented, though, is that each uniquely
named area encountered by the linker results in creation of three
symbols that can be can be (and are) referenced by any object
file. These are the area name itself and a 'base' and 'limit' pair
which point at the start address of the first area of that name
when the program is loaded and the address of the byte after the
last occurrence of that area, for example, the area 'C$$Code'
would generate the symbols 'C$$Code', 'C$$Code$$Base' and
'C$$Code$$Limit'. The area 'C$$Debug' adds the symbols 'C$$Debug',
'C$$Debug$$Base' and 'C$$Debug$$Limit' to the linker's symbol
table.

What was said in the preceding paragraph also applies to 'common'
blocks. These are areas just like any other, but they are handled
slightly differently in that all common block areas with the same
name are overlaid on one another with the size of the common block
being that of the largest instance of the common block. Just as
with other areas, three symbols are created for each common block
that can be used in programs: the common block name and a 'base'
and 'limit' pair based on that name, for example, a common block
called 'acorn' would add the symbols 'acorn', 'acorn$$Base' and
'acorn$$Limit' to the linker's tables.

If the '-zo' C compiler option is used, each function in the
object code has its own uniquely-name area and this results in an
explosion in the number of area symbols generated. Normally this
would not be a problem except for the extra memory required to
hold these symbols, but it results in the low-level debugging
table created by the linker becoming flooded with what is, in the
author's opinion, totally useless symbol information. Drlink's
solution to this problem is not to include any symbols generated
for areas apart from those for common blocks in the low-level
debugging table.

There are other symbols that 'link' defines internally but these
have not been seen in any AOF files yet and so they have not be
included in Drlink.


Linker sets (and constructor/destructor lists)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As of Drlink 0.42, Drlink is capable of creating implicitly
linked lists of tables from its object files. This feature is an
extension of the C++ constructor/destructor lists. These are only
likely to be of use to experienced programmers.

Within certain programs it is useful to be able to provide
support for extending features of a program without requiring any
changes to the code. The best example of this is the initial use
of the linker sets, the C++ constructor list. When a C program
starts its static data is already initialised before 'main' is run.
However, when a C++ program starts, the initialisation of its
static data may involve the execution of more complex code - the
object constructors. There can be any number of constructors and
these must all be located and initialised. The C++ system uses
a special pair of symbols to locate the routines that will be
used to constructor objects. The '__link' symbol is defined
within every object file as a local symbol. Being a local symbol,
it can therefore be defined in multiple files. The first word
pointed to by each of these symbols will be chained together to
the next. The start of this list is assigned to the word pointed
to by the '__head' symbol. The '__head' symbol is a global
symbol which is only defined in the routine used to initialise
the C++ system (this is actually used in the ______main routine
in the C++ system, but this is an implementation issue rather
than a linker-provided feature). This feature is enabled by the
'-c++' switch.

Linker sets are a generalisation of this feature, enabled by
the '-linkersets' switch. Rather than being restricted to the
single '__link' and '__head' symbols, the linker can generate
a chain of any number of symbols beginning with these names.
Only lists which match the names suffix would be related. That
is, the list starting at '__head_foo' and made up of the
local symbols named '__link_foo', would be distinct from the
list starting at '__head_bar' and made up of the local symbols
named '__link_bar'.

For example, if you had a list of messages you wanted to be
printed by an application when it started up, you could use
a linker set to chain these together. Each file which wanted
to provide a message would include code similar to the
following :

static struct _linkerset_s {
  struct _linkerset_s *next;
  char *message;
} __link_message = { NULL, "Message to be displayed" };

Within the main code, where the message was to be displayed,
the list could be iterated through with code similar to the
following :

struct _linkerset_s {
  struct _linkerset_s *next;
  char *message;
} *__head_message;

int show_messages(void)
{
  struct _linkerset_s *ls;
  for (ls = __head_message; ls; ls = ls->next)
    printf("%s\n", ls->message);
}

It is important to note that only the first word of the linker set
is important to drlink. The above examples only use a single 
additional word, but beyond the first element the structure is
completely user defined.


Differences Between Drlink and Link
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Drlink is based on the version of 'link' that comes with
release 3 of the C compiler but there are a number of features of
'link' that are missing or that have been changed slightly. The
idea is that Drlink will be used to link 'ordinary' programs and
not any of the more exotic types that the Acorn linker can handle,
for example, programs that use overlays.

First, the missing features:

1)  Drlink does not support overlays (the '-overlay' option).

2)  The entry address of the program cannot be specified (the
    option '-entry').

3)  The old debug option '-dbug' is not supported.

4)  The option to print a list of cross references between areas
    has not be included (option '-xref').

5)  It does not support unnamed common blocks.

6)  The 'link' documentation contains vague references to Un*x
    'Aout' format files. Drlink does not handle these.

The known differences are:

1)  The low level debugging tables do not have as many entries in
    them as the ones generated by 'link'. 'link' includes entries
    for symbols for every single area in the executable program
    but Drlink leaves out all of these apart from the ones for
    'common' blocks.

2)  There are a number of undocumented built-in linker symbols
    available in 'link' such as '_esdata' that Drlink does not
    include.

3)  The default program name created by the linker is '!Runimage'
    and not 'aif'.

4)  If the '-bin' option is used to create a binary file and the
    entry point is not the first instruction in the program,
    Drlink adds a branch to that address at the start of the
    program.

5)  The link edit commands are different to link's.

6)  The partially-linked AOF files produced by Drlink are not the
    same as those produced by link. They do not contain the zero-
    length area 'Aout$$Common'. The relocations in the AOF file
    are a mixture of type-1 and type-2 rather than being all
    type-2.

7)  '-base' behaves differently. With link, the filetype of a file
    where '-base' is used is 'absolute'. Drlink makes such files
    untyped and gives them load and execution addresses.

8)  Strong symbol definitions are more fully supported.
 
The extensions to the Acorn release 3 link are:

1)  If running under a task window or in the 'F12' CLI, Drlink can
    extend its wimpslot.

2)  It can removed unreferenced areas from the executable program.

3)  Drlink supports extended command lines.

4)  It can scan libraries more than once.

5)  Debugging tables can be selectively included in the image
    file.

6)  Warning, error and fatal error messages can be displayed in a
    'throwback' window.

7)  The starting address of the read/write part of the image file
    can be defined by means of a linker option.
    
8)  A map of areas contained in the executable image file can be
    written to a file.

9)  It can produce a listing of symbols in the image file.

10) It can align the end of the read-only portion of the image fle
    on a page boundary.

11) It partially supports AOF version 3 (enough to link C and C++
    programs) and generates AIF version 3 headers on image files.

In all other respects, Drlink should behave in exactly the same
way as 'link', hopefully apart from some known bugs in 'link'.
There are probably other subtle differences in the way the linkers
behave but these are not known.


Change Record
~~~~~~~~~~~~~
Drlink 0.20 - First release version.

Drlink 0.21
-  Added support for type-2 relocations.
-  Fixed problem with paths with multiple directories in
   filenames.
-  Speeded up linker a bit.

Drlink 0.22
-  Fixed bug where symbolic debug tables were left out of the
   image file if '-nounused' was used.
-  Changed way linker orders areas to more closely match that of
   'link'.
-  Added option '-keepdebug' to selectively include debugging
   information from object files in image file.
-  Allowed filenames supplied for options '-lib' and '-keepdebug'
   to be enclosed in double quotes. This will, in fact, work on
   any option.

Drlink 0.23
-  Added 'link edit' commands (the '-edit' option).
-  Added code to allow 'back-to-front' filenames.
-  Now sets a return code of 12 if a link fails.
-  Fixed bug in '-keepdebug' code where a buffer was overflowing
   and overwriting anything that followed it, e.g. amu.

Drlink 0.24
-  Made 'verbose' mode list the names of the external references
   being satisfied and the files containing those references when
   loading library members.
-  Linker now prints a warning message about and lists files
   specified on '-keepdebug' that were not loaded.
-  A problem with extended command lines containing rubbish at the
   end of the line has been fixed.

Drlink 0.25
-  Fixed bug where the offset of the program entry point within
   the entry point's area was being set to zero.
-  Fixed bug in '-nounused' code where references to areas in
   type-2 relocations were not being handled correctly.
-  Fixed bug to do with filenames that include a path variable
   that only showed up with RISC OS 2.
-  Added the option to create partially-linked AOF files (option
   '-aof').
-  Added 'throwback' support (option '-throwback'). Warning, error
   and fatal error messages can be displayed in a 'throwback'
   window.
-  Added warning to documentation concerning the use of the C
   compiler option '-zo'.

Drlink 0.26
-  Improved linker's performance in large links.
-  Improved memory management.
-  Added options '-base' and '-data' to allow the start addresses
   of code and data part of the image file to be specified.
-  Added option '-areamap' to allow map of areas in image file to
   be written to a file.
-  Added code to circumvent problem with the DDEUtils command
   '*prefix' where the linker cannot find files where a path is
   included as part of the filename, for example, 'C:O.Stubs',
   after '*prefix' has been used.

Drlink 0.26a - Bug fix version
-  Fixed bug introduced in 0.26 where -aof code stopped working.
-  Programmed around problem affecting files from Objasm that
   contain debug tables where the tables contain an invalid 'AL'
   attribute.
-  RISC OS 2 filenames with paths finally sorted out I hope!
-  Recompiled with the latest and greatest version of the
   compiler.

Drlink 0.27
-  Fixed bug where unresolved references to weak external symbols
   were being included in the list of relocations at the end of
   relocatable modules.
-  Fixed bug in '-nounused' which could cause addressing
   exceptions if an AOF file contained type-2 relocations.
-  Fixed bug where type-2 relocations in an object file that is
   used as part of a partially-linked AOF file were sometimes
   being relocated incorrectly.
-  Added option '-acornmap' to allow printing of symbol listing in
   more-or-less the same format as that used by 'link'.
-  Added option '-pagealign' to allow end of read-only part of
   image to be aligned on a page boundary (useful for DDT).
-  Changed symbol listing so that the addresses of symbols in
   relocatable modules are expressed as an offset from the start
   of the module instead of an address.
-  Corrected handling of common blocks.
-  Added code to allow code and data areas to have the 'common
   definition' area attribute.
-  Changed handling of zero length areas. Previously Drlink
   ignored these completely.
-  The linker will now produce a list of unresolved weak external
   references if option '-verbose' is used instead of just
   mentioning the fact.
-  Corrected low level debug table and symbol listing code so that
   they no longer include symbols from areas omitted from the image
   file.
-  Added support for 'strong' symbol definitions.
-  Added some AOF V3 support.

Drlink 0.28
-  Added option '-leaveweak' to stop linker resolving weak external
   references from libraries (so that it behaves as per AOF 3 docs).
-  Changed headers on image file to AIF v3 headers.
-  Added option -C++ to instruct linker to carry out C++-specific
   operations concerned with constructors and destructors. The
   linker does not yet expand C++ mangled names into their full
   versions.
-  Added support for 'old style' libraries so that FORTRAN 77
   programs can be linked.
-  Fixed bug where relocation info for type-2 relocations was
   missed out in relocatable AIF files and relocatable modules.
-  Improved memory management when linker is running out of memory.

Drlink 0.29
-  Added symbols 'Image$$CodeBase', 'Image$$CodeLimit',
   'Image$$DataBase' and 'Image$$DataLimit' required by FORTRAN 77
   programs. These will only be included if 'old style' libraries
   are read.

Drlink 0.30
-  Made code StrongARM compatible.
-  Added support for 'based' areas.
-  Added support for areas not aligned on a word boundary.
-  Added option '-quiet' which stops linker from printing the
   'Drlink AOF Linker' message.
-  Added support for the relocation of instruction sequences.
-  Fixed bug affecting symbols which had the 'common reference'
   attribute set.
-  Fixed two bugs in partially-linked AOF file support which
   stopped partially-linked files working with C release 5.
-  Fixed bug causing addressing exception when option '-symbol'
   was used when creating a partially-linked AOF file.
-  Fixed bug in C++ code where areas containing constructors
   and destructors could be deleted if option '-nounused' was
   used.
-  Added code to handle 'strong symbol' case that was missed out
   when strong symbol support was added.

Drlink 0.31
-  Fixed bug in library search code.
-  Added option '-revmap'.

Drlink 0.32
-  Fixed problem where very long symbol names (300 characters!)
   caused the linker to fail in various places.

Drlink 0.33
-  Fixed problem in code that produces area maps where area names
   longer than about 200 characters were causing the linker to
   die.
-  Added option '-gcc' to stop linker removing GCC-specific areas
   from the image file when '-nounused' is used.
-  Increased the maximum length filename that the linker will
   handle to 500 characters.

Drlink 0.34
-  Linker can now be compiled to run under RiscBSD and Linux (but
   it still links only AOF files).

[...]

Drlink 0.41
- Support big-endian platforms (like Mac OS X).  This does not
  mean support for big-endian AOF/ALF files.
  
Drlink 0.42 (based on work from Justin Fletcher)
- Fix for C++ constructor/destructor lists corrupting image
  (Norcroft case).
- Added support for -linkersets in line with the functionality of
  recent versions of Norcroft Link.
- Src code cleanups.

Drlink 0.43
- Support for host platforms where sizeof(void *) != 4.

Drlink 0.44
- Option -strict: treat warnings as errors.
- Support for natural filenames for object and library files.
- Fixed problem hiding symbol from an AOF file stored in ALF
  library.


Copyright
~~~~~~~~~
The software and the documentation that goes with it is
Copyright © David Daniels 1993, 1994, 1995, 1996, 1997, 1998.
Copyright © GCCSDK Developers 2001, 2002, 2003, 2004, 2005, 2006.

Around 2001 David Daniels issued the source code of Drlink under
GPL.

-EOF-
